docs(kernel): reduce the 429 and 503 details fences in error-handling.mdx to what producers emit - #17190

Fixes #16937

Clause-②: no — this diff touches only content/docs/**. No package's files[] ships that path (the one package.json mentioning content/docs is @objectstack/plugin-webhooks, and only in its description string; its files[] is ["dist","README.md","CHANGELOG.md"]), so the published surface is byte-unchanged. Positive control for that reading: dist appears in 70 package files[], content/docs in zero. No changeset for the same reason.

Measured on origin/main at fd5cff209f, which is where this branch is cut. All line numbers below are from that tree, located by text rather than by the card's pre-#15855 numbers.

What changed

Three JSON fences in content/docs/protocol/kernel/error-handling.mdx now show what a producer actually emits. Net 3 insertions, 13 deletions, one file.

Why — the 429 pair

Both 429 emitters build the same exhaustive two-member object literal, so anything else those fences named was not in the bag by construction, not merely absent from a word search:

packages/runtime/src/endpoint-policy.ts:356
packages/runtime/src/security/inbound-rate-limit.ts:359
  details: { retryAfterSeconds: retryAfterSec, resetAt: new Date(decision.resetAt).toISOString() }

resetAt is the member the page never mentioned: re-measured at this commit it has 16 hits in packages/**, including both producer lines. The card reported 19 at 9a89a0040; the count has drifted since, the control still fires, and 16 is what this tree reads.

Why — the 503 fence, which was measure-first

The card asserted "no 503 producer on this tree emits a details bag at all" and neither the triage seat nor the dispatching seat had verified it. Measured here, with a positive control on the same corpus for every zero:

SERVICE_UNAVAILABLE is a live, produced code — 72 code: 'SERVICE_UNAVAILABLE' construction sites, and it is absent from scripts/error-status-unpinned-baseline.json (which lists codes no producer pins a status for). The five real construction sites emit { code, message } and nothing more:

packages/objectql/src/action-activation.ts:269
packages/triggers/trigger-api/src/api-trigger.ts:204
packages/plugins/plugin-auth/src/auth-plugin.ts:2260
packages/plugins/plugin-auth/src/auth-plugin.ts:2883

One boundary worth recording, because it is the nearest thing to a counter-example: the generic classification path in packages/types/src/thrown-http-error.ts:233 can attach a details bag at any status, and sendError's extra argument lets a caller pass one. But that path's members are exhaustively { code?, issues?, fields? } — never reason, retryAfterSeconds or estimated_completion — and no 503 caller passes details. So all three documented members are unbacked on both paths. Dropping the bag is what was measured; nothing was invented to fill the absence, and the section itself stays.

What was deliberately NOT changed

The QUOTA_EXCEEDED fence is untouched. The dispatching seat asked for this to be established before assuming the same mould, and the measurement says the defect is a different one:

The triage seat's reading was right that the 30 packages/** hits are "almost all SMS_QUOTA_EXCEEDED_*", a different symbol — but the residue is not nothing. The three bare hits are the StandardErrorCode catalog declaration at packages/spec/src/api/errors.zod.ts:106, a deliberately-wrong waiver fixture at packages/spec/src/api/error-code-ledger.test.ts:132, and scripts/error-status-unpinned-baseline.json, which lists QUOTA_EXCEEDED under the note "StandardErrorCode members documented with an HTTP status that NO producer this gate can read declares a status for".

So the code is registered but unproduced. Route 1 has no answer here — there is no emitted shape to reduce the fence to — and the resolutions (retire the code under ADR-0049, build the producer, or mark the section illustrative) are a contract decision rather than a docs edit. Per the ruling, "如果根本没有生产者,那这个 fence 的问题不是「成员写错」而是「整个错误码是编的」——⚠️ 那是另一张卡,不是本卡的修法". Spun out to #17187 rather than guessed at here.

Line 729 (:739 pre-diff) is untouched — const retryAfter = data.error.details.retryAfterSeconds || 1;. It is correct post-#15855 and is the page's firing control, proving the page can name the producer right.

The HTTP header blocks are untouched — out of scope for a card about details members. They carry the same class of defect (X-RateLimit-* set by no producer; Retry-After on the 503 block set by no 503 producer), measured with controls and filed separately as #17188.

Verification

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 40 commands for this path; all 40 were run and reconciled with --ran:

Run reconciliation — 40 derived, 40 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 40 derived famil(ies) accounted for — 40 run, 0 NOT-MEASURED.

All 40 green, including pnpm check:error-status-conformance, pnpm check:doc-anchors, pnpm check:docs-single-h1, pnpm check:doc-authoring and pnpm check:nul-bytes. Two of them first refused with an explicit unbuilt-prerequisite verdict rather than a finding (check:doc-formula-expressions exit 3, "Nothing was measured"; check:skill-examples on an unbuilt client-react/dist); both were re-run green after turbo run build for the packages they named.

Repo-wide pnpm lint is CI's run, not this PR's: eslint reports this file as "File ignored because no matching configuration was supplied" — read from eslint's own config via --format json over 1 file — and the config never mentions mdx, so this diff cannot move any eslint verdict.

Control-byte self-scan on the edited file: 0 hits.

Reviewer note

The measurements above are all greppable in one pass; the load-bearing asymmetry is that SERVICE_UNAVAILABLE is absent from scripts/error-status-unpinned-baseline.json while QUOTA_EXCEEDED is present. That file is machine-maintained and shrink-only, which is why it is cited here rather than a hand-run grep.

🤖 Generated with Claude Code

https://claude.ai/code/session_012GKcPZbMoGq7WPzKLfRBTU

Generated by Claude Code